---
title: "Quickstart"
---

This guide will walk you through setting up DBHub and connecting it to an AI tool for the first time. We'll use demo mode to get started quickly, then show you how to connect to your own database.

## Prerequisites

Before starting, ensure you have:
- Node.js 18+ installed (for NPM method) **OR** Docker installed
- Access to an AI tool (Claude Desktop, Claude Code, Cursor, or VS Code)
- Optionally: A PostgreSQL, MySQL, or other supported database

## Step 1: Start DBHub in Demo Mode

Let's start with demo mode to verify everything works:

<Tabs>
  <Tab title="NPM">
    ```bash
    npx @bytebase/dbhub --transport stdio --demo
    ```
  </Tab>

  <Tab title="Docker">
    ```bash
    docker run -i --rm bytebase/dbhub --transport stdio --demo
    ```
  </Tab>
</Tabs>

<Note>
Demo mode includes a sample SQLite "employee" database with realistic data - perfect for testing without setting up a real database connection.
</Note>

The server will start and display output indicating it's ready to accept connections.

## Step 2: Connect with Your AI Tool

Choose your AI tool and follow the setup instructions:

### Claude Desktop

Edit your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

<Tabs>
  <Tab title="Docker Demo">
    ```json claude_desktop_config.json
    {
      "mcpServers": {
        "dbhub-demo": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "bytebase/dbhub",
            "--transport",
            "stdio",
            "--demo"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="NPX Demo">
    ```json claude_desktop_config.json
    {
      "mcpServers": {
        "dbhub-demo": {
          "command": "npx",
          "args": [
            "-y",
            "@bytebase/dbhub",
            "--transport",
            "stdio",
            "--demo"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="NPX with Your Database">
    ```json claude_desktop_config.json
    {
      "mcpServers": {
        "dbhub-postgres": {
          "command": "npx",
          "args": [
            "-y",
            "@bytebase/dbhub",
            "--transport",
            "stdio",
            "--dsn",
            "postgres://user:password@localhost:5432/dbname?sslmode=disable"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
Claude Desktop only supports `stdio` transport.
</Note>

### Cursor

Install DBHub in Cursor using the deeplink or manual configuration:

**Quick Install (Deeplink):**
```
cursor://anysphere.cursor-deeplink/mcp/install?name=dbhub&config=eyJjb21tYW5kIjoibnB4IEBieXRlYmFzZS9kYmh1YiIsImVudiI6eyJUUkFOU1BPUlQiOiJzdGRpbyIsIkRTTiI6InBvc3RncmVzOi8vdXNlcjpwYXNzd29yZEBsb2NhbGhvc3Q6NTQzMi9kYm5hbWU/c3NsbW9kZT1kaXNhYmxlIiwiUkVBRE9OTFkiOiJ0cnVlIn19
```

Copy the link above and paste it into your browser to install DBHub in Cursor.

**Manual Configuration:**

Configure in Cursor's MCP settings or use environment variables:

```json
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "TRANSPORT": "stdio",
        "DSN": "postgres://user:password@localhost:5432/dbname?sslmode=disable",
        "READONLY": "true"
      }
    }
  }
}
```

<Note>
Cursor supports both `stdio` and `http` transports. Make sure to use [Agent mode](https://docs.cursor.com/chat/agent) to access MCP tools.
</Note>

### Claude Code

Create or update `.claude/mcp.json` in your project:

```json .claude/mcp.json
{
  "servers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp",
      "type": "http"
    }
  }
}
```

Start DBHub server with HTTP transport:

```bash
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/mydb" --readonly
```

<Note>
Claude Code uses HTTP transport. The server must be running before you can use it.
</Note>

### VS Code with Copilot

Create `.vscode/mcp.json` in your project:

```json .vscode/mcp.json
{
  "servers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp",
      "type": "http"
    }
  },
  "inputs": []
}
```

Start DBHub server:

```bash
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/mydb" --readonly
```

**Optional: Add Copilot Instructions**

Create `.github/copilot-instructions.md` to provide context:

```markdown .github/copilot-instructions.md
## Database Access

This project provides an MCP server (DBHub) for secure database access.

In read-only mode (recommended):
- `SELECT * FROM users LIMIT 10;`
- `SHOW TABLES;`
- `DESCRIBE table_name;`

Use the `execute_sql` tool to run queries.
```

<Note>
VS Code with GitHub Copilot supports both `stdio` and `http` transports.
</Note>

## Step 3: Restart Your AI Tool

After updating the configuration:

1. **Claude Desktop/Cursor**: Completely quit and restart the application
2. **Claude Code/VS Code**: Reload the window or restart VS Code
3. Verify the MCP server appears in the tools/resources list

## Step 4: Try It Out

Try these example prompts in your AI tool:

<AccordionGroup>
  <Accordion icon="database" title="List available schemas">
    ```
    What schemas are available in the database?
    ```

    Claude will use the `db://schemas` resource to list all schemas.
  </Accordion>

  <Accordion icon="table" title="Show tables in a schema">
    ```
    What tables are in the public schema?
    ```

    Claude will use the `db://schemas/public/tables` resource.
  </Accordion>

  <Accordion icon="magnifying-glass" title="Query employee data">
    ```
    Show me the top 5 employees by salary
    ```

    Claude will generate and execute SQL like:
    ```sql
    SELECT * FROM employees ORDER BY salary DESC LIMIT 5;
    ```
  </Accordion>

  <Accordion icon="chart-line" title="Analyze data">
    ```
    How many employees are in each department?
    ```

    Claude will generate an appropriate SQL query:
    ```sql
    SELECT dept_name, COUNT(*) as employee_count
    FROM dept_emp
    JOIN departments USING (dept_no)
    WHERE to_date = '9999-01-01'
    GROUP BY dept_name
    ORDER BY employee_count DESC;
    ```
  </Accordion>
</AccordionGroup>

## Step 5: Connect to Your Own Database

Once you've verified DBHub works in demo mode, connect it to your actual database:

### Update Your Configuration

<Tabs>
  <Tab title="PostgreSQL">
    ```json
    {
      "mcpServers": {
        "dbhub-prod": {
          "command": "npx",
          "args": [
            "-y",
            "@bytebase/dbhub",
            "--transport",
            "stdio",
            "--dsn",
            "postgres://user:password@localhost:5432/mydb?sslmode=disable",
            "--readonly"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="MySQL">
    ```json
    {
      "mcpServers": {
        "dbhub-mysql": {
          "command": "npx",
          "args": [
            "-y",
            "@bytebase/dbhub",
            "--transport",
            "stdio",
            "--dsn",
            "mysql://root:password@localhost:3306/mydb?sslmode=disable",
            "--readonly"
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="SQLite">
    ```json
    {
      "mcpServers": {
        "dbhub-sqlite": {
          "command": "npx",
          "args": [
            "-y",
            "@bytebase/dbhub",
            "--transport",
            "stdio",
            "--dsn",
            "sqlite:///path/to/database.db",
            "--readonly"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
We added `--readonly` flag for safety. This restricts the AI to only SELECT queries - perfect for production databases!
</Tip>

### Using Environment Variables

For better security, avoid putting passwords in the config file:

1. Create a `.env` file:
```bash .env
DSN=postgres://user:password@localhost:5432/mydb?sslmode=disable
READONLY=true
```

2. Update your configuration to use environment variables:
```json
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio"],
      "env": {
        "DSN": "postgres://user:password@localhost:5432/mydb?sslmode=disable",
        "READONLY": "true"
      }
    }
  }
}
```

## Common Use Cases

### Explore Database Schema

```
Show me the structure of the users table
```

Claude will retrieve the table structure including columns, types, and constraints.

### Generate SQL Queries

```
Write a query to find all users who signed up in the last 30 days
```

Claude will generate appropriate SQL based on your schema.

### Data Analysis

```
Analyze the distribution of order amounts by customer segment
```

Claude will create and execute analytical queries to answer your question.

### Debug Issues

```
Why is this query slow: SELECT * FROM orders WHERE customer_id = 123
```

Claude can examine indexes and suggest optimizations.

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-Database Setup" icon="database" href="/config/multi-database">
    Connect to multiple databases simultaneously
  </Card>

  <Card title="Read-Only Mode" icon="lock" href="/features/readonly-mode">
    Secure your production databases
  </Card>

  <Card title="SSH Tunneling" icon="shield" href="/features/ssh-tunnel">
    Connect through bastion hosts
  </Card>

  <Card title="DSN Configuration" icon="link" href="/config/dsn">
    Database connection string formats
  </Card>
</CardGroup>

## Troubleshooting

### MCP Server Not Appearing

If the server doesn't appear in Claude Desktop:

1. Check the configuration file syntax (valid JSON)
2. Verify the file path is correct
3. Restart Claude Desktop completely
4. Check Claude Desktop logs for errors

### Connection Errors

If you see database connection errors:

1. Verify your DSN is correct
2. Test the connection using a database client
3. Check firewall rules
4. For Docker, use `host.docker.internal` instead of `localhost`

### Permission Errors

If queries fail with permission errors:

1. Verify the database user has the necessary permissions
2. Check if the database requires SSL (add `?sslmode=require` to DSN)
3. Ensure the user can access the schema you're querying
